Skip to content

docs: initialize blueprint development structure#171

Merged
laurigates merged 5 commits intomainfrom
feat/blueprint-init
Apr 8, 2026
Merged

docs: initialize blueprint development structure#171
laurigates merged 5 commits intomainfrom
feat/blueprint-init

Conversation

@laurigates
Copy link
Copy Markdown
Owner

@laurigates laurigates commented Apr 8, 2026

Summary

  • Initialize Blueprint Development v3.2.0 with manifest, task registry, and directory structure
  • Migrate 13 existing ADRs from docs/adr/ to docs/adrs/ (blueprint convention)
  • Derive PRD-001 (project overview) from README, CLAUDE.md, and component docs
  • Derive 3 new ADRs from git history: profile-based packages (0014), gitleaks (0015), shell completions (0016)
  • Create 3 PRPs for future work: Fish shell, NixOS, Sketchybar
  • Generate 5 new Claude rules: development, testing, document-management, chezmoi-conventions, dependency-management
  • Update CLAUDE.md with blueprint references

Test plan

  • chezmoi diff ~/.claude shows no changes (rules synced)
  • chezmoi apply --dry-run runs clean
  • pre-commit run --all-files passes (actionlint warnings are pre-existing)
  • docs/adrs/README.md index includes all 16 ADRs
  • docs/blueprint/manifest.json is valid JSON with v3.2.0 format

Follow-up

  • Run /configure:select for infrastructure standards audit (separate PR)
  • Run /blueprint:adr-validate after merge to check cross-references
  • Create GitHub issues for PRD-001 and PRPs (GitHub MCP auth was unavailable)

🤖 Generated with Claude Code

laurigates and others added 5 commits April 7, 2026 20:23
@laurigates @claude
docs: initialize blueprint and migrate ADRs to docs/adrs/
97a9d26 
- Initialize Blueprint Development structure (v3.2.0)
- Create docs/blueprint/ with manifest.json and README
- Migrate 13 ADRs + README from docs/adr/ to docs/adrs/
- Fix internal cross-reference in ADR-0011
- Add initial rules: development.md, testing.md, document-management.md
- Enable decision detection (document-management rule)
- Add docs/blueprint/work-orders/ to .gitignore

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@laurigates @claude
docs: derive PRD-001 and complete ADR migration
afaec00 
- Generate project-overview PRD from README, CLAUDE.md, and components docs
- Remove old docs/adr/ directory (files already in docs/adrs/ from previous commit)
- Update manifest with PRD-001 entry and ID registry

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@laurigates @claude
docs: derive ADRs and PRPs from git history analysis
e21bb5b 
- ADR-0014: Profile-based package registry (packages.toml + profiles.toml)
- ADR-0015: Gitleaks replacing detect-secrets for secret scanning
- ADR-0016: Shell completion auto-generation pattern
- PRP-001: Fish shell migration (experimental → primary)
- PRP-002: NixOS implementation plan
- PRP-003: Sketchybar macOS integration
- Update ADR README index with new entries
- Update manifest with derive-plans task completion and ID registry

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@laurigates @claude
docs: derive Claude rules from git history patterns
98b6fe6 
- chezmoi-conventions.md: template patterns, exact_/private_ prefixes,
  deprecation handling, source-vs-target workflow
- dependency-management.md: mise backend selection, Homebrew profiles,
  MCP server management, upgrade patterns
- Update manifest with derive-rules task completion

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@laurigates @claude
docs: update CLAUDE.md with blueprint integration
c80496a 
- Add Blueprint Documentation section with PRD, ADRs, PRPs, and manifest references
- Add docs/blueprint/README.md to sub-documentation list
- Update manifest claude-md task registry

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@github-actions github-actions bot added documentation Improvements or additions to documentation claude security mcp size/l labels Apr 8, 2026
@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Apr 8, 2026

⚠️ Broken Links Detected

Summary

Status Count
🔍 Total 128
✅ Successful 121
⏳ Timeouts 0
🔀 Redirected 0
👻 Excluded 5
❓ Unknown 0
🚫 Errors 2

Errors per input

Errors in exact_dot_claude/docs/blueprint-development/README.md

Please fix the broken links before merging.

@laurigates laurigates merged commit e65fe19 into main Apr 8, 2026
5 of 8 checks passed
@laurigates laurigates deleted the feat/blueprint-init branch April 8, 2026 07:20
@claude
Copy link
Copy Markdown
Contributor

claude bot commented Apr 8, 2026

PR Review: docs: initialize blueprint development structure

Summary

This PR introduces Blueprint v3.2.0 infrastructure for managing project documentation. It establishes a structured approach to PRDs (Product Requirements), ADRs (Architecture Decision Records), and PRPs (Product Requirement Plans), along with new Claude rules.

Code Quality & Best Practices

Strengths:

  • Well-organized documentation hierarchy (docs/prds/, docs/adrs/, docs/prps/, docs/blueprint/)
  • Consistent directory naming: rename from docs/adr/ to docs/adrs/ follows plural convention
  • Properly updated cross-reference in ADR-0011 (line 145: docs/adr/ → docs/adrs/)
  • Clean manifest.json with task registry tracking derivation progress
  • New Claude rules (development.md, testing.md, chezmoi-conventions.md, dependency-management.md, document-management.md) are concise and actionable
  • Appropriate .gitignore addition for docs/blueprint/work-orders/ (security consideration)

Suggestions:

  • The chezmoi-conventions.md:31 says chezmoi apply --force ~/.claude but the existing CLAUDE.md uses chezmoi apply -v ~/.claude. Consider aligning these.

Potential Issues

Documentation claims non-existent commands:
The CLAUDE.md update references Blueprint commands (/blueprint:status, /blueprint:execute, /blueprint:derive-plans) but no corresponding command definitions exist in exact_dot_claude/commands/. Consider either:

  1. Adding these commands in this PR, or
  2. Documenting them as "planned" rather than available, or
  3. Creating follow-up issues to implement them

Unrelated change detected:
The working tree shows .github/scripts/generate-allowed-tools.sh with a permission change (644→755). This appears unrelated to the Blueprint initialization and should either be:

  • Removed from this PR (if unintentional)
  • Added as a separate commit with appropriate message (if intentional)

Security Concerns

  • None identified. The .gitignore entry for work-orders is a good practice for task-specific files that may contain sensitive details.

Test Coverage

The PR follows the test plan outlined:

  • chezmoi diff ~/.claude verification
  • chezmoi apply --dry-run clean run
  • pre-commit run --all-files passes
  • ADR README index completeness (verified: all 16 ADRs indexed)
  • manifest.json validity (verified: valid JSON, correct format_version)

Performance

No performance concerns. This is a documentation-only change with no runtime impact.

Overall

Good PR that establishes a solid documentation foundation. The main concern is the forward-reference to Blueprint commands that don't yet exist. Consider addressing this before merge to avoid documentation drift.

🤖 Automated review by Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

claude documentation Improvements or additions to documentation mcp security size/l

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@laurigates